home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib.fmt / c / Fs_Dispatch.man < prev    next >
Encoding:
Text File  |  1989-04-05  |  9.4 KB  |  267 lines
  1.  
  2.  
  3.  
  4. Fs_Dispatch           C Library Procedures            Fs_Dispatch
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NNAAMMEE
  11.      Fs_Dispatch, Fs_EventHandlerCreate,  Fs_EventHandlerDestroy,
  12.      Fs_EventHandlerData,              Fs_EventHandlerChangeData,
  13.      Fs_TimeoutHandlerCreate, Fs_TimeoutHandlerDestroy  -  stream
  14.      event and timeout dispatcher routines.
  15.  
  16. SSYYNNOOPPSSIISS
  17.      ##iinncclluuddee <<ffss..hh>>
  18.  
  19.      void
  20.      FFss__DDiissppaattcchh()
  21.  
  22.      void
  23.      FFss__EEvveennttHHaannddlleerrCCrreeaattee(_s_t_r_e_a_m_I_D, _e_v_e_n_t_M_a_s_k, _p_r_o_c, _c_l_i_e_n_t_D_a_t_a)
  24.  
  25.      void
  26.      FFss__EEvveennttHHaannddlleerrDDeessttrrooyy(_s_t_r_e_a_m_I_D)
  27.  
  28.      void
  29.      FFss__EEvveennttHHaannddlleerrDDaattaa(_s_t_r_e_a_m_I_D)
  30.  
  31.      ClientData
  32.      FFss__EEvveennttHHaannddlleerrCChhaannggeeDDaattaa(_s_t_r_e_a_m_I_D, _c_l_i_e_n_t_D_a_t_a)
  33.  
  34.      ##iinncclluuddee <<ttiimmee..hh>>
  35.  
  36.      Fs_TimeoutHandler
  37.      FFss__TTiimmeeoouuttHHaannddlleerrCCrreeaattee(_t_i_m_e, _r_e_l_a_t_i_v_e_T_i_m_e, _p_r_o_c, _c_l_i_e_n_t_D_a_t_a)
  38.  
  39.      void
  40.      FFss__TTiimmeeoouuttHHaannddlleerrDDeessttrrooyy(ttookkeenn)
  41.  
  42.  
  43. AARRGGUUMMEENNTTSS
  44.      int                 _s_t_r_e_a_m_I_D       (in)      Specifies   the
  45.                                                   stream       to
  46.                                                   create an event
  47.                                                   handler for.
  48.  
  49.      int                 _e_v_e_n_t_M_a_s_k      (in)      Mask indicating
  50.                                                   which events on
  51.                                                   _s_t_r_e_a_m_I_D are to
  52.                                                   be processed by
  53.                                                   _p_r_o_c.  Can   be
  54.                                                   the  bitwise OR
  55.                                                   of FFSS__RREEAADDAABBLLEE,
  56.                                                   FFSS__WWRRIITTAABBLLEE and
  57.                                                   FFSS__EEXXCCEEPPTTIIOONN.
  58.  
  59.      void                (*_p_r_o_c)()      (in)      Procedure    to
  60.  
  61.  
  62.  
  63. Sprite v.1.0         Printed:  April 5, 1989                    1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Fs_Dispatch           C Library Procedures            Fs_Dispatch
  71.  
  72.  
  73.  
  74.                                                   invoke when one
  75.                                                   of  the  events
  76.                                                   in    _e_v_e_n_t_M_a_s_k
  77.                                                   occurs   on   a
  78.                                                   stream  or when
  79.                                                   a       timeout
  80.                                                   period expires.
  81.  
  82.      ClientData          _c_l_i_e_n_t_D_a_t_a     (in)      Uninterpreted
  83.                                                   value passed to
  84.                                                   _p_r_o_c when it is
  85.                                                   invoked.
  86.  
  87.      Time                _t_i_m_e           (in)      The    absolute
  88.                                                   time  when _p_r_o_c
  89.                                                   should       be
  90.                                                   called  or  the
  91.                                                   time   interval
  92.                                                   between   calls
  93.                                                   to _p_r_o_c.
  94.  
  95.      Boolean             _r_e_l_a_t_i_v_e_T_i_m_e   (in)      If  TTRRUUEE,  then
  96.                                                   _t_i_m_e  specifies
  97.                                                   a      interval
  98.                                                   between   calls
  99.                                                   to  _p_r_o_c.    If
  100.                                                   FFAALLSSEE,     then
  101.                                                   _t_i_m_e  specifies
  102.                                                   the    absolute
  103.                                                   time when  _p_r_o_c
  104.                                                   should       be
  105.                                                   called.
  106.  
  107.      Fs_TimeoutHandler   _t_o_k_e_n          (in)      A   token    to
  108.                                                   identify a par-
  109.                                                   ticular timeout
  110.                                                   handler  so  it
  111.                                                   can   be   des-
  112.                                                   troyed.
  113.  
  114. _________________________________________________________________
  115.  
  116. DDEESSCCRRIIPPTTIIOONN
  117.      These routines implement a dispatcher for events on  streams
  118.      and  timeouts. An event occurs when the stream becomes read-
  119.      able, writable or has an exception  condition  pending.  The
  120.      dispatcher  handles  the  details  of  waiting for events to
  121.      occur on streams. When an event occurs, the dispatcher calls
  122.      a  routine  supplied  by the clients to deal with the event.
  123.      Also, timeout handlers can be  created  so  that  a  client-
  124.      supplied routine can be called at a specific time or at reg-
  125.      ular intervals.
  126.  
  127.      The   dispatcher   must   be    initialized    by    calling
  128.  
  129.  
  130.  
  131. Sprite v.1.0         Printed:  April 5, 1989                    2
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138. Fs_Dispatch           C Library Procedures            Fs_Dispatch
  139.  
  140.  
  141.  
  142.      FFss__EEvveennttHHaannddlleerrCCrreeaattee  and/or FFss__TTiimmeeoouuttHHaannddlleerrCCrreeaattee before
  143.      FFss__DDiissppaattcchh is called.  FFss__DDiissppaattcchh causes  the  process  to
  144.      wait  until  an event occurs on a stream or until a time-out
  145.      occurs. At that point, it  calls  the  appropriate  handler.
  146.      Once  the  handler  completes,  FFss__DDiissppaattcchh  returns  to its
  147.      caller. To have the dispatcher remain in control, do
  148.  
  149.               while (TRUE) {
  150.                Fs_Dispatch();
  151.               }
  152.  
  153.      FFss__EEvveennttHHaannddlleerrCCrreeaattee is used to cause the procedure _p_r_o_c to
  154.      be  called when one or more of the events in _e_v_e_n_t_M_a_s_k occur
  155.      on _s_t_r_e_a_m_I_D. Only one procedure may be attached to a  stream
  156.      so  it  should  be able to deal with all of the event types.
  157.      _P_r_o_c should be declared as:
  158.  
  159.           void
  160.           proc(clientData, streamID, eventMask)
  161.               ClientData clientData;
  162.               int        streamID;
  163.               int        eventMask;
  164.           {
  165.           }
  166.      FFss__EEvveennttHHaannddlleerrDDaattaa can be used to get the _c_l_i_e_n_t_D_a_t_a  asso-
  167.      ciated  with _s_t_r_e_a_m_I_D. FFss__EEvveennttHHaannddlleerrCChhaannggeeDDaattaa can be used
  168.      to change  the  _c_l_i_e_n_t_D_a_t_a  associated  with  _s_t_r_e_a_m_I_D.  The
  169.      handler can be destroyed with FFss__EEvveennttHHaannddlleerrDDeessttrrooyy.
  170.  
  171.      In addition, a time-out routine can be setup  to  be  called
  172.      using FFss__TTiimmeeoouuttHHaannddlleerrCCrreeaattee. If _r_e_l_a_t_i_v_e_T_i_m_e is TTRRUUEE, then
  173.      _t_i_m_e specifies an interval (e.g. one hour) from the  current
  174.      time  that  _p_r_o_c  will  be called at.  When _p_r_o_c returns, it
  175.      will automatically be rescheduled to be called at  the  next
  176.      interval. If _p_r_o_c doesn't need to be called again, it should
  177.      call FFss__TTiimmeeoouuttHHaannddlleerrDDeessttrrooyy.  If  _r_e_l_a_t_i_v_e_T_i_m_e  is  FFAALLSSEE,
  178.      then  _t_i_m_e  specifies a specific time (e.g., 3:15pm 17 Sept.
  179.      1987) that _p_r_o_c will be called at. _P_r_o_c is called once -  it
  180.      is  not  automatically  rescheduled to be called again. How-
  181.      ever, it could call FFss__TTiimmeeoouuttHHaannddlleerrCCrreeaattee to cause  it  to
  182.      be called again.  _P_r_o_c should be declared as:
  183.  
  184.           void
  185.           proc(clientData, time)
  186.               ClientData clientData;
  187.               Time  Time;
  188.           {
  189.           }
  190.      For example, to have EExxaammpplleeRRoouuttiinnee called in 1 minute  from
  191.      now and every minute after that, the call should be:
  192.  
  193.             Fs_TimeoutHandlerCreate(time_OneMinute, TRUE, ExampleRoutine, clientData);
  194.  
  195.  
  196.  
  197. Sprite v.1.0         Printed:  April 5, 1989                    3
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204. Fs_Dispatch           C Library Procedures            Fs_Dispatch
  205.  
  206.  
  207.  
  208.      FFss__TTiimmeeoouuttHHaannddlleerrCCrreeaattee returns a token that must  be  saved
  209.      if FFss__TTiimmeeoouuttHHaannddlleerrDDeessttrrooyy is to be called.
  210.  
  211.  
  212. KKEEYYWWOORRDDSS
  213.      callback, client data, dispatcher, stream ID, time
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263. Sprite v.1.0         Printed:  April 5, 1989                    4
  264.  
  265.  
  266.  
  267.